Adds typed, collection-local initialData and initialDataUpdatedAt support to eager Query Collections. Initial Query responses now materialize immediately as collection rows while retaining TanStack Query's cache identity, freshness, and wrapped-response semantics.

Root Cause

Query Collections already materialized data preloaded into a QueryClient, but they could not declare initial data per collection. Applications sharing one client across many collections therefore had to choose between overly broad client defaults and imperative cache seeding. Forwarding defaults unchanged was also unsafe for on-demand subsets and placeholder data: neither has collection-wide row-membership semantics.

Approach

• Add typed top-level initialData and initialDataUpdatedAt options using the original Query response type.
• Forward those options only for eager observers, then reuse the existing select, materialization, and row-ownership pipeline.
• Reject explicit collection-level initial data in on-demand mode and suppress client-wide initial-data defaults for derived subset observers.
• Suppress placeholderData defaults because placeholder results are observer-local UI state, not Query cache data suitable for normalized rows.
• Document the authority, lifecycle, wrapped-response, write, ownership, and persistence semantics.

Key Invariants

• The Query cache remains authoritative; existing cached or hydrated data wins over a later initializer.
• Exact Query keys identify shared documents, even when collections share a QueryClient.
• select materializes rows without replacing the original wrapped response in the Query cache.
• Stale initial rows remain available during refetch and reconcile through normal ownership rules.
• Placeholder data and collection-wide initializers never become rows for arbitrary on-demand subsets.
• Persistence needs no new format or temporary-row metadata.

Non-goals

• Materializing placeholderData as DB rows.
• Defining a subset-aware initializer for on-demand collections.
• Giving each collection a private cache document when it uses the same exact Query key.
• Changing direct-write or persistence formats.

Trade-offs

On-demand mode rejects explicit initial-data options rather than guessing subset membership. Callers that know an exact derived key can still seed or hydrate that Query cache entry. Eager mode suppresses placeholder defaults to keep observer presentation state out of the collection's shared normalized state.

Verification

pnpm vitest run packages/query-db-collection/tests/query.test.ts --maxWorkers=1
pnpm --filter @tanstack/query-db-collection build
pnpm --filter @tanstack/query-db-collection lint
git diff --check

The focused Query Collection suite covers fresh and stale initial data, function initializers, wrapped response projection, shared clients and exact keys, existing-cache precedence, on-demand rejection/default suppression, and placeholder-default suppression. Lint passes with existing warnings.

Files changed

• packages/query-db-collection/src/query.ts — adds the public options and observer initialization policy.
• packages/query-db-collection/src/errors.ts — adds the on-demand configuration error.
• packages/query-db-collection/tests/query.test.ts — adds initialization and isolation coverage.
• docs/collections/query-collection.md — documents usage and user-visible semantics.
• docs/collections/query-initial-placeholder-data-design.md — records authority, ownership, transitions, writes, and persistence decisions.
• .changeset/young-cats-initialize.md — records the minor package feature.

Closes #346. Advances #1643.

Summary by CodeRabbit

• New Features

  • Added eager collection support for TanStack Query’s initialData and initialDataUpdatedAt.
  • Initial data is immediately available as collection rows while preserving wrapped response data.
  • Fresh initial data can prevent an unnecessary fetch; stale data is refreshed and reconciled with server results.
  • Added safeguards so placeholder data is not materialized as collection rows.
  • Added clear errors when initial data is used with on-demand collections.

• Documentation

  • Documented initial data behavior, cache precedence, wrapped responses, and placeholder data limitations.